Crate libafl_bolts

Expand description

Welcome to LibAFL_bolts

LibAFL_bolts: OS and Fuzzer Dev’s Libary Collection.

The libafl_bolts crate exposes a lot of low-level features of LibAFL for projects that are unrelated to fuzzing, or just fuzzers completely different to LibAFL. Some cross-platform things in bolts include (but are not limited to):

SerdeAnyMap: a map that stores and retrieves elements by type and is serializable and deserializable
ShMem: A cross-platform (Windows, Linux, Android, MacOS) shared memory implementation
LLMP: A fast, lock-free IPC mechanism via SharedMap
Core_affinity: A maintained version of core_affinity that can be used to get core information and bind processes to cores
Rands: Fast random number generators for fuzzing (like RomuRand)
MiniBSOD: get and print information about the current process state including important registers.
Tuples: Haskel-like compile-time tuple lists
Os: OS specific stuff like signal handling, windows exception handling, pipes, and helpers for fork

LibAFL_bolts is written and maintained by

Contributing

For bugs, feel free to open issues or contact us directly. Thank you for your support. <3

Even though we will gladly assist you in finishing up your PR, try to

keep all the crates compiling with stable rust (hide the eventual non-stable code under cfgs)
run cargo fmt on your code before pushing
check the output of cargo clippy --all or ./clippy.sh
run cargo build --no-default-features to check for no_std compatibility (and possibly add #[cfg(feature = "std")]) to hide parts of your code.

Some of the parts in this list may be hard, don’t be afraid to open a PR if you cannot fix them by yourself, so we can help.

License

^{Licensed under either of Apache License, Version
2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.}
_{Dependencies under more restrictive licenses, such as GPL or AGPL, can be enabled
using the respective feature in each crate when it is present, such as the
'agpl' feature of the libafl crate.}

Feature Flags

General Features

std (enabled by default) — Enables features that need rust’s std lib to work, like print, env, … support
alloc (enabled by default) — Enables all features that allocate in no_std
derive (enabled by default) — Provide the #[derive(SerdeAny)] macro.
rand_trait (enabled by default) — If set, libafl_bolt’s rand implementations will implement rand::Rng
python — Will build the pyo3 bindings
prelude (enabled by default) — Expose libafl::prelude for direct access to all types without additional use directives
cli — Expose libafl_bolts::cli for easy commandline parsing of common fuzzer settings
qemu_cli — Enables extra commandline flags for qemu-based fuzzers in cli
frida_cli — Enables extra commandline flags for frida-based fuzzers in cli
errors_backtrace — Stores the backtraces of all generated Errors. Good for debugging, but may come with a slight performance hit.
gzip (enabled by default) — Enables gzip compression in certain parts of the lib
xxh3 (enabled by default) — Replaces ahash with the potentially faster xxh3 in some parts of the lib. This yields a stable and fast hash, but may increase the resulting binary size slightly This also enables certain hashing and rand features in no_std no-alloc.

SerdeAny features

serdeany_autoreg (enabled by default) — Automatically register all #[derive(SerdeAny)] types at startup.

LLMP features

llmp_bind_public — If set, llmp will bind to 0.0.0.0, allowing cross-device communication. Binds to localhost by default.
llmp_compression (enabled by default) — Enables llmp compression using GZip
llmp_debug — Enables debug output for LLMP (also needs a logger installed)
llmp_small_maps (enabled by default) — Reduces the initial map size for llmp

Modules

anymap
Poor-rust-man’s downcasts to have AnyMap
bolts_prelude
The purpose of this module is to alleviate imports of the bolts by adding a glob import.
build_id
Based on https://github.com/alecmocatta/build_id (C) Alec Mocatta alec@mocatta.net under license MIT or Apache 2
cli
A one-size-fits-most approach to defining runtime behavior of LibAFL fuzzers
compress
Compression of events passed between a broker and clients. Currently we use the gzip compression algorithm for its fast decompression performance.
core_affinity
This crate manages CPU affinities.
cpu
Architecture agnostic processor features
fs
LibAFL functionality for filesystem interaction
launcherDeprecated
Dummy module informing potential users that the launcher module has moved out of libafl_bolts into libafl::events::launcher.
llmp
A library for low level message passing
math
Math-related functions that we commonly (or at least sometimes) need
minibsod
Implements a mini-bsod generator. It dumps all important registers and prints a stacktrace. You may use the crate::os::unix_signals::ucontext function to get a ucontext_t.
os
Operating System specific abstractions
ownedref
Wrappers that abstracts references (or pointers) and owned data accesses.
prelude
The purpose of this module is to alleviate imports of many components by adding a glob import.
pybind
rands
The random number generators of LibAFL
serdeany
Poor-rust-man’s downcasts for stuff we send over the wire (or shared maps)
shmem
A generic shared memory region to be used by any functions (queues or feedbacks too.)
staterestore
Stores and restores state when a client needs to relaunch. Uses a ShMem up to a threshold, then write to disk.
tuples
Compiletime lists/tuples used throughout the LibAFL universe

Macros

create_anymap_for_trait
Create AnyMap and NamedAnyMap for a given trait
create_register
Register a SerdeAny type in the RegistryBuilder
create_serde_registry_for_trait
Creates the serde registry for serialization and deserialization of SerdeAny. Each element needs to be registered so that it can be deserialized.
impl_asany
Implement AsAny for a type
impl_serde_pyobjectwrapper
impl_serdeany
Implement a SerdeAny, registering it in the RegistryBuilder when on std
tuple_for_each
Iterate over a tuple, executing the given expr for each element.
tuple_for_each_mut
Iterate over a tuple, executing the given expr for each element, granting mut access.
unwrap_me_body
unwrap_me_mut_body

Structs

ClientId
The client ID == the sender id.
SimpleFdLogger
A simple logger struct that logs to a RawFd when used with log::set_logger.
SimpleStderrLogger
A simple logger struct that logs to stderr when used with log::set_logger.
SimpleStdoutLogger
A simple logger struct that logs to stdout when used with log::set_logger.

Enums

Error
Main error struct for LibAFL

Statics

LIBAFL_STDERR_LOGGER
Stderr logger
LIBAFL_STDOUT_LOGGER
Stdout logger

Traits

AsIter
Create an Iterator from a reference
AsIterMut
Create an Iterator from a mutable reference
AsMutSlice
Can be converted to a mutable slice
AsSlice
Can be converted to a slice
HasLen
Has a length field
HasRefCnt
Has a ref count
IntoOwned
Trait to convert into an Owned type
Named
We need fixed names for many parts of this lib.
Truncate
Trait to truncate slices and maps to a new size

Functions

current_milliseconds
Gets current milliseconds since UNIX_EPOCH
current_nanos
Gets current nanoseconds since UNIX_EPOCH
current_time
Current time
format_duration_hms
Format a Duration into a HMS string
hash_std
Hashes the input with a given hash, depending on features: xxh3_64 if the xxh3 feature is used, /// else ahash.
hasher_std
Returns the hasher for the input with a given hash, depending on features: xxh3_64 if the xxh3 feature is used, /// else ahash.

Type Aliases

ErrorBacktrace
Error Backtrace type when errors_backtrace feature is enabled (== backtrace::Backtrace)

Derive Macros

SerdeAny
Derive macro to implement SerdeAny, to use a type in a SerdeAnyMap